Skip to content

docs: add "Have It Your Way" plugin dev note#608

Merged
johnnygreco merged 5 commits into
mainfrom
johnny/docs/plugins-dev-note
May 13, 2026
Merged

docs: add "Have It Your Way" plugin dev note#608
johnnygreco merged 5 commits into
mainfrom
johnny/docs/plugins-dev-note

Conversation

@johnnygreco

@johnnygreco johnnygreco commented May 6, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a new dev note introducing Data Designer's plugin framework now that plugins have graduated out of experimental mode. The PR is now rebased onto main and targets main directly instead of the former stacked plugin-docs branch.

Changes

Added

Changed

  • Adds the new dev note to the MkDocs navigation in mkdocs.yml
  • Adds reusable devnote dek and floated-image styling in docs/css/style.css
  • Keeps the existing cleanup that removes redundant quotes from two devnote nav labels

Attention Areas

Reviewers: Please pay special attention to the following:

  • have-it-your-way.md - review the plugin framing, example code, and links into the plugin docs and recipe pages.
  • style.css - review the new reusable devnote image/dek styling across desktop and mobile widths.

Description updated with AI

@github-actions

github-actions Bot commented May 6, 2026

Copy link
Copy Markdown
Contributor

MkDocs preview: https://06ffdba6.dd-docs-preview.pages.dev

Fern preview: https://nvidia-preview-pr-608.docs.buildwithfern.com/nemo/datadesigner​

Notebook tutorials are rendered without execution outputs in previews.

@johnnygreco johnnygreco force-pushed the johnny/docs/plugins-out-of-experimental-mode branch from c49880f to aae652e Compare May 6, 2026 20:33
@johnnygreco johnnygreco marked this pull request as ready for review May 6, 2026 22:08
@johnnygreco johnnygreco requested a review from a team as a code owner May 6, 2026 22:08
@greptile-apps

greptile-apps Bot commented May 6, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR adds a new "Have It Your Way" dev note introducing Data Designer's plugin framework now that plugins have graduated from experimental, along with reusable CSS helpers for devnote image layout and the removal of the experimental warning banners from the plugin reference pages.

  • The dev note is added in both MkDocs (docs/devnotes/posts/have-it-your-way.md) and Fern (fern/versions/v0.5.8/pages/devnotes/posts/have-it-your-way.mdx) formats, with navigation entries correctly placed at the most-recent-first position in both mkdocs.yml and fern/versions/v0.5.8.yml.
  • CSS additions in docs/css/style.css introduce devnote-dek, devnote-float-right, devnote-section-graphic, and devnote-clear utility classes with a responsive breakpoint at 60em; experimental warning banners are removed from three Fern plugin pages (overview.mdx, example.mdx, filesystem_seed_reader.mdx).

Confidence Score: 5/5

Documentation-only change; no runtime code is modified. Safe to merge.

All changes are documentation, CSS styling, and navigation config. The plugin framework code itself is untouched. The one finding is a missing helper function reference in an illustrative code example inside a blog post, which has no effect on the built product.

No files require special attention beyond the illustrative code snippet in the dev note.

Important Files Changed

Filename Overview
docs/devnotes/posts/have-it-your-way.md New dev note introducing the plugin framework. Well-structured, but the impl.py code example calls extract_markdown_sections() which is neither imported nor defined anywhere in the shown snippet.
fern/versions/v0.5.8/pages/devnotes/posts/have-it-your-way.mdx Fern mirror of the dev note. Same extract_markdown_sections() issue as the MkDocs version; also has a minor import order difference vs. the MkDocs counterpart.
docs/css/style.css Adds devnote-dek, devnote-float-right, devnote-section-graphic, and devnote-clear helper classes plus a mobile responsive breakpoint; no issues found.
fern/versions/v0.5.8/pages/plugins/overview.mdx Removes experimental warning banner and refreshes the intro paragraph and plugin type descriptions; clean change.
mkdocs.yml Adds have-it-your-way nav entry at the correct most-recent-first position.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User installs plugin package] --> B[Entry point registered\nvia pyproject.toml]
    B --> C[Data Designer discovers\nplugin at startup]
    C --> D[User imports plugin\nconfig class]
    D --> E[User adds to\nDataDesignerConfigBuilder]
    E --> F{Plugin type?}
    F -->|Seed Reader| G[build_manifest\nhydrate_row]
    F -->|Column Generator| H[generate column\nwith dependency ordering]
    F -->|Processor| I[transform records\nbefore/after generation]
    G --> J[Data Designer executes\nnormal workflow]
    H --> J
    I --> J
Loading
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/devnotes/posts/have-it-your-way.md:231-255
**`extract_markdown_sections` is undefined in the shown code**

The `impl.py` block is framed as a walkthrough of a complete file, but `extract_markdown_sections` is called without being imported or defined anywhere in the snippet. A reader copying this code would get a `NameError` immediately. The prose does note "the parser can still be a normal helper function," but there is no indication of where that function comes from — whether it should be defined earlier in `impl.py`, imported from a sibling module, or supplied by the user. The same gap exists in the Fern mirror at `fern/versions/v0.5.8/pages/devnotes/posts/have-it-your-way.mdx`. Adding a brief comment inside the code block or a preceding prose sentence pointing readers to the recipe link for the complete version would resolve the ambiguity.

Reviews (10): Last reviewed commit: "docs: link v0.6.0 release" | Re-trigger Greptile

Comment thread mkdocs.yml
@johnnygreco johnnygreco force-pushed the johnny/docs/plugins-dev-note branch from f3bd9b9 to 9dbb9e5 Compare May 6, 2026 22:18
@johnnygreco johnnygreco changed the base branch from johnny/docs/plugins-out-of-experimental-mode to main May 6, 2026 22:18
eric-tramel
eric-tramel previously approved these changes May 7, 2026
nabinchha
nabinchha previously approved these changes May 7, 2026

@nabinchha nabinchha left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added one minor comment/question. Also should this post mention custom column generator somewhere?

Comment thread docs/devnotes/posts/have-it-your-way.md
@johnnygreco johnnygreco dismissed stale reviews from nabinchha and eric-tramel via 806c94a May 12, 2026 01:52
@johnnygreco johnnygreco force-pushed the johnny/docs/plugins-dev-note branch 2 times, most recently from 806c94a to 4bc9834 Compare May 12, 2026 01:59
@johnnygreco

Copy link
Copy Markdown
Contributor Author

Thanks @nabinchha, good call. I added a short note at the end of the “Where Plugins Fit” section that points readers to custom columns as the right starting point for prototyping column-generator behavior or for one-off project-specific columns. It also says to promote that logic to a column generator plugin once it needs a stable config schema, tests, packaging, docs, or reuse across teams.

@johnnygreco johnnygreco force-pushed the johnny/docs/plugins-dev-note branch from 6c9a3ce to 995a725 Compare May 13, 2026 17:19
nabinchha
nabinchha previously approved these changes May 13, 2026
@johnnygreco johnnygreco force-pushed the johnny/docs/plugins-dev-note branch from efda041 to 8ecacb8 Compare May 13, 2026 18:49
@johnnygreco johnnygreco merged commit ef761b8 into main May 13, 2026
50 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants